/*
 * Copyright 2012 Fabian Wenzelmann
 * 
 * This file is part of Recognition-Procedures-for-Boolean-Functions.
 * 
 * Recognition-Procedures-for-Boolean-Functions is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 * 
 * Recognition-Procedures-for-Boolean-Functions is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 * 
 * You should have received a copy of the GNU General Public License
 * along with Recognition-Procedures-for-Boolean-Functions.  If not, see <http://www.gnu.org/licenses/>.
 */

package de.wenzelmf.booleanFunction.util;

import java.io.Serializable;
import java.util.Collection;
import java.util.List;

/**
 * The Java library contains an stack implementation that is based on the Vector class, and
 * thus based on an array. But there are other implementations possible,
 * especially without size constraints and without copying the whole content to a new array
 * when the old array is too small.
 * <br>
 * This interface defines an abstract stack. It extends the java List interface and defines
 * the methods required for a stack, such as <code>push</code> and <code>pop</code>.
 * <br>
 * So all classes that implement this interface implement a LIFO (last-in-first-out) stack.
 * <br>
 * Note that the implementations of <code>addAll</code> in the java Stack and LinkedList
 * implementations differ. If you use the <code>addAll</code> method on an empty
 * {@link LinkedListStack} with the elements [1, 2] the <code>pop</code> method returns 1.
 * <br>
 * If you do the same thing with a {@link JavaStack} the <code>pop</code> method returns 2.
 * <br>
 * The specification for this interface is the following: A constructor that takes another Collection should
 * call the {@link #pushAll(Collection)} method. So the last element of the Collection should be
 * the first that is returned by the first <code>pop</code> call.
 * <br>
 * You should not use the <code>addAll</code> method, but instead {@link #pushAll(Collection)}.
 * In my eyes this is more reasonable for stacks.
 * 
 * @author Fabian Wenzelmann
 * @version 1.0
 *
 */
public interface IStack<T> extends List<T>, Cloneable, Serializable
{
	
	/**
	 * Tests whether this stack is empty or not.
	 * 
	 * @return <code>true</code> if the stack is empty, <code>false</code> otherwise.
	 */
	public boolean empty();
	
	/**
	 * Returns the element on the top of this stack, but does not remove it.
	 * 
	 * @return Element on the top of this stack.
	 */
	public T peek();
	
	/**
	 * Returns the top of this stack and removes this element.
	 * 
	 * @return The top element of this stack.
	 */
	public T pop();
	
	/**
	 * Push an item onto this stack, so it becomes the new head of the stack.
	 * 
	 * @param item The item to push.
	 */
	public void push(T item);
	
	/**
	 * Pushes all elements from the collection to this stack.
	 * 
	 * The effect of this method should be the same as:
	 * <br>
	 * <code>for(T e : c) {
	 * 		push(e);
	 * }</code>
	 * <br>
	 * So the last element of the collection is the next element returned by the {@link #pop()}
	 * method.
	 * 
	 * @param c The collection containing the elements to push.
	 */
	public void pushAll(Collection<? extends T> c);
	
	//public int search(Object o);
	
}
